









<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>iBaGuice - Simple DAO</title>
    <link rel="stylesheet" href="./css/maven-theme.css" type="text/css" />
    <link rel="stylesheet" href="./css/maven-base.css" type="text/css"/>
    <link rel="stylesheet" href="./css/prettify.css" type="text/css"/>
    <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
    <script type="text/javascript" src="./js/prettify.js"></script>
    <script type="text/javascript" src="./js/niftycube.js"></script>
    <script type="text/javascript">
        window.onload=function() {
            Nifty("div\#wrapper", "big");
            Nifty("div#breadcrumbs", "small");
            Nifty("div\#navcolumn", "small");
            Nifty("div.source", "medium");
            prettyPrint();
        }
    </script>
          <meta name="author" content="The iBaGuice Team" />
          </head>
  <body>
    <div id="wrapper">
        <div id="banner">
                      <a href="http://ibaguice.googlecode.com/svn/site/1.0-beta-2/index.html" id="bannerLeft"  >
    
                                            <img src="images/logo.png" alt="iBaGuice: enjoy the power of iBatis + Google Guice" />
    
            </a>
                            <div class="clear">
            <hr/>
          </div>
        </div>
        <div id="breadcrumbs">
              
  

  
    
            
  
    
            <div class="xleft">
        <span id="publishDate">Last Published: 2010-03-01</span>
                  &nbsp;| <span id="projectVersion">Version: 1.0-beta-2</span>
                      </div>
                <div class="xright">      
  

  
    
            
  
    
  </div>
          <div class="clear">
            <hr/>
          </div>
        </div>
        <div id="leftColumn">
          <div id="navcolumn">
               
  

  
    
            
  
    
                       <h5>iBaGuice - Main</h5>
            <ul>
              
    <li class="none">
                    <a href="index.html">Introduction</a>
          </li>
              
    <li class="none">
                    <a href="core.html">The Core components</a>
          </li>
              
    <li class="none">
              <strong>The DAO Module</strong>
        </li>
          </ul>
              <h5>Data Sources</h5>
            <ul>
              
    <li class="none">
                    <a href="datasource.html#Unpooled_Data_Source_Provider">Unpooled Data Source Provider</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Pooled_Data_Source_Provider">Pooled Data Source Provider</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#JNDI_Data_Source_Provider">JNDI Data Source Provider</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Basic_Data_Source_Provider">Basic Data Source Provider</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Shared_Pool_Data_Source">Shared Pool Data Source</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Per_User_Pool_DataSource">Per User Pool DataSource</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Connection_Pool_Data_Source_driver_adapter">Connection Pool Data Source driver adapter</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#C3P0_Provider">C3P0 Provider</a>
          </li>
          </ul>
              <h5>Caching support</h5>
            <ul>
              
    <li class="none">
                    <a href="caching.html#Ehcache">Ehcache</a>
          </li>
              
    <li class="none">
                    <a href="caching.html#Hazelcast">Hazelcast</a>
          </li>
              
    <li class="none">
                    <a href="caching.html#JBoss_Cache">JBoss Cache</a>
          </li>
              
    <li class="none">
                    <a href="caching.html#Memcached">Memcached</a>
          </li>
              
    <li class="none">
                    <a href="caching.html#OSCache">OSCache</a>
          </li>
          </ul>
              <h5>Miscellaneous</h5>
            <ul>
              
    <li class="none">
                    <a href="stats.html">Project stats</a>
          </li>
              
    <li class="none">
                    <a href="iBaGuice-1.0-beta-2.pdf">PDF Manual</a>
          </li>
          </ul>
              <h5>Project Documentation</h5>
            <ul>
              
                
                    
                  
                  
                  
                  
                  
                  
                  
                  
                  
                  
                  
              
        <li class="collapsed">
                    <a href="project-info.html">Project Information</a>
                </li>
              
                
                    
                  
                  
                  
              
        <li class="collapsed">
                    <a href="project-reports.html">Project Reports</a>
                </li>
          </ul>
              <h5>Modules</h5>
            <ul>
              
    <li class="none">
                    <a href="ibaguice-core/index.html">Core</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-dao/index.html">DAO</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-c3p0/index.html">c3p0</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-dbcp13/index.html">Apache DBCP</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-oscache/index.html">OSCache</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-memcached/index.html">Memcached</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-ehcache/index.html">Ehcache</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-jbosscache/index.html">JBoss Cache</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-hazelcast/index.html">Hazelcast Cache</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-samples/index.html">Samples</a>
          </li>
          </ul>
              <h5>External Links</h5>
            <ul>
              
    <li class="none">
                    <a href="">Project Page</a>
          </li>
              
    <li class="none">
                    <a href="http://ibatis.apache.org/" class="externalLink">iBatis</a>
          </li>
              
    <li class="none">
                    <a href="../google-guice/">Google Guice</a>
          </li>
          </ul>
                                               <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
            <img class="poweredBy"
                 alt="Built by Maven"
                 src="./images/logos/maven-feather.png"
                 width="90"
                 height="30"
                 border="1" />
          </a>
                           
  

  
    
            
  
    
            </div>
        </div>
        <div id="bodyColumn">
          <div id="contentBox">
            <div class="section"><h2>iBaGuice DAO</h2>
<p>The package <tt>com.google.code.ibaguice.dao</tt> is not a DAO framework built on top of iBatis but rather contains small components that help users to avoid rewriting the same stuff in every project they need to realize a DAO layer using iBatis.</p>
<p>Users that want to use the <i>DAO</i> support of <i>iBaGuice</i> have to add the following dependency:</p>
<div class="source"><pre>&lt;dependencies&gt;
    ...
    &lt;dependency&gt;
        &lt;groupId&gt;com.google.code.ibaguice&lt;/groupId&gt;
        &lt;artifactId&gt;ibaguice-dao&lt;/artifactId&gt;
        &lt;version&gt;XX.XX&lt;/version&gt;
    &lt;/dependency&gt;
    ...
&lt;/dependencies&gt;</pre>
</div>
<div class="section"><h3>The Abstract DAO class</h3>
<p>Simply, the <tt>com.google.code.ibaguice.dao.AbstractDao</tt> is an abstract class where the <tt>org.apache.ibatis.session.SqlSessionFactory</tt> is automatically injected by <i>Google Guice</i>.</p>
<p>So users want to enjoy the combined power of iBatis+Guice have just to extend that class and let Guice cretaing instances. For exampe, given the following <tt>com.acme.FooDAO</tt> implementation class:</p>
<div class="source"><pre>package com.acme;

import com.google.inject.Singleton;
import com.google.code.ibaguice.dao.*;

@Singleton
public final class FooDAOImpl extends AbstractDao implements FooDAO {

    ...

}</pre>
</div>
<p>keeping in mind the way how iBaGuice <a href="core.html">creates</a> the iBatis bindings, users can easily obtain the instance of <tt>com.acme.FooDAO</tt> in the following way:</p>
<div class="source"><pre>Class&lt;? extends Provider&lt;DataSource&gt;&gt; dataSourceProviderClass = [...];
Class&lt;? extends Provider&lt;TransactionFactory&gt;&gt; txFactoryProviderClass = [...];

Injector injector = Guice.createInjector(
    new SqlSessionFactoryModule(dataSourceProviderClass, txFactoryProviderClass),
    new Module() {
        public void configure(Binder binder) {
            binder.bind(FooDAO.class).to(FooDAOImpl.class);
        }
    });
);

FooDAO fooDAO = injector.getInstance(FooDAO.class);</pre>
</div>
</div>
<div class="section"><h3>@Transactional</h3>
<p>Using a proper <i>AOP</i> interceptor, users can drastically reduce the boilerplate code into their DAOs.</p>
<p>Let's take in consideration the following code snippet:</p>
<div class="source"><pre>package com.acme;

import com.google.inject.Singleton;
import com.google.code.ibaguice.dao.*;

@Singleton
public final class FooDAOImpl extends AbstractDao implements FooDAO {

    public void doFooBar() throws Exception {
        SqlSession session = this.getSqlSessionFactory().openSession(ExecutorType.BATCH, TransactionIsolationLevel.READ_UNCOMMITTED);
        try {
            FooMapper fooMapper = session.getMapper(FooMapper.class);
            fooMapper.doFoo();

            BarMapper barMapper = session.getMapper(BarMapper.class);
            barMapper.doBar();

            session.commit();
        } catch (Throwable t) {
            session.rollback();
            throw new Exception(&quot;Something went wrong&quot;, t);
        } finally {
            session.close();
        }
    }

}</pre>
</div>
<p>Introducing the <tt>com.google.code.ibaguice.dao.AbstractTransactionalDao</tt> class and the <tt>com.google.code.ibaguice.dao.Transactional</tt> annotation, users can eliminate recursive code patterns, trasforming the previous method in the tidy following:</p>
<div class="source"><pre>package com.acme;

import com.google.inject.Singleton;
import com.google.code.ibaguice.dao.*;

@Singleton
public final class FooDAOImpl extends AbstractTransactionalDao implements FooDAO {

    @com.google.code.ibaguice.dao.Transactional(ExecutorType.BATCH, IsolationLevel.READ_UNCOMMITTED)
    public void doFooBar() {
        FooMapper fooMapper = this.getMapper(FooMapper.class);
        fooMapper.doFoo();

        BarMapper barMapper = this.getMapper(BarMapper.class);
        barMapper.doBar();
    }

}</pre>
</div>
<p>to obtain this behavior, users have first to bind the interceptor using the provided <tt>com.google.code.ibaguice.dao.TransactionalModule</tt> module:</p>
<div class="source"><pre>Class&lt;? extends Provider&lt;DataSource&gt;&gt; dataSourceProviderClass = [...];
Class&lt;? extends Provider&lt;TransactionFactory&gt;&gt; txFactoryProviderClass = [...];

Injector injector = Guice.createInjector(
    new SqlSessionFactoryModule(dataSourceProviderClass, txFactoryProviderClass),
    new TransactionalModule(),
    new Module() {
        public void configure(Binder binder) {
            binder.bind(FooDAO.class).to(FooDAOImpl.class);
        }
    });
);

FooDAO fooDAO = injector.getInstance(FooDAO.class);</pre>
</div>
<p>Then, annotating methods with the <tt>com.google.code.ibaguice.dao.Transactional</tt> annotation, that supports the following parameter:</p>
<table class="bodyTable"><tbody><tr class="a"><th align="left">Property</th>
<th align="center">Default</th>
<th align="center">Description</th>
</tr>
<tr class="b"><td align="left">autoCommit</td>
<td align="center">false</td>
<td align="center">the iBatis auto commit policy</td>
</tr>
<tr class="a"><td align="left">executorType</td>
<td align="center">org.apache.ibatis.session.ExecutorType.SIMPLE</td>
<td align="center">the iBatis executor type</td>
</tr>
<tr class="b"><td align="left">isolationLevel</td>
<td align="center">com.google.code.ibaguice.dao.IsolationLevel.NOT_SPECIFIED</td>
<td align="center">the transaction isolation level</td>
</tr>
<tr class="a"><td align="left">force</td>
<td align="center">false</td>
<td align="center">Flag to indicate that iBatis has to force the transaction <tt>commit()</tt></td>
</tr>
<tr class="b"><td align="left">rethrowExceptionsAs</td>
<td align="center">Exception.class</td>
<td align="center">rethrow caught exceptions as new Exception (maybe a proper layer exception)</td>
</tr>
</tbody>
</table>
<p><b>Note</b> If <tt>@com.google.code.ibaguice.dao.Transactional.isolationLevel()</tt> is equals to <tt>com.google.code.ibaguice.dao.IsolationLevel.NOT_SPECIFIED</tt>, then the <tt>org.apache.ibatis.session.SqlSession</tt> will be open using the <tt>@com.google.code.ibaguice.dao.Transactional.executorType()</tt> and <tt>@com.google.code.ibaguice.dao.Transactional.autoCommit()</tt> values.</p>
<p>The <tt>com.google.code.ibaguice.dao.AbstractTransactionalDao</tt> extends the <tt>com.google.code.ibaguice.dao.AbstractDao</tt>, so users that need to use directly the <tt>org.apache.ibatis.session.SqlSessionFactory</tt> are free to use it.</p>
<p><b>Note</b> If, because of your system design, you're not allowed to extends the <tt>com.google.code.ibaguice.dao.AbstractTransactionalDao</tt>, but still want to enjoy the power of <tt>com.google.code.ibaguice.dao.Transactional</tt>, inject into your classes the <tt>com.google.code.ibaguice.dao.SqlSessionRegistry</tt>:</p>
<div class="source"><pre>package com.acme;

import com.google.inject.Singleton;
import com.google.code.ibaguice.dao.*;

@Singleton
public final class FooDAOImpl extends MyBarClass implements FooDAO {

    @Inject
    private SqlSessionRegistry sqlSessionRegistry;

    @com.google.code.ibaguice.dao.Transactional
    public void doFooBar() {
        FooMapper fooMapper = this.sqlSessionRegistry.getMapper(FooMapper.class);
        fooMapper.doFoo();

        BarMapper barMapper = this.sqlSessionRegistry.getMapper(BarMapper.class);
        barMapper.doBar();
    }

}</pre>
</div>
<div class="section"><h4>Nested transactions</h4>
<p>The <tt>com.google.code.ibaguice.dao.Transactional</tt> annotation is nicely handled to support inner transactional method declaration; given a simple service class:</p>
<div class="source"><pre>class ServiceA {

    @com.google.code.ibaguice.dao.Transactional
    public void method() {
        ...
    }

}</pre>
</div>
<p>and another one:</p>
<div class="source"><pre>class ServiceB {

    @com.google.code.ibaguice.dao.Transactional
    public void method() {
        ...
    }

}</pre>
</div>
<p>they could be called inside a new composite one:</p>
<div class="source"><pre>class CompositeService {

    ServiceA serviceA;

    ServiceB serviceB;

    @com.google.code.ibaguice.dao.Transactional
    public void method() {
        ...
        serviceA.method();
        ...
        serviceB.method();
        ...
    }

}</pre>
</div>
<p>In this case, <tt>ServiceA</tt> and <tt>ServiceB</tt> can be used isolatedly, but <tt>serviceA.method()</tt> and <tt>serviceB.method()</tt> calls in the <tt>CompositeService</tt> will be managed into the same session, even if annotated to start a new transaction.</p>
</div>
</div>
</div>

          </div>
        </div>
        <div class="clear">
          <hr/>
        </div>
        <div id="footer">
          <div class="xright">Copyright &#169;         
   
          2010.
    
      All Rights Reserved.    
  

  
    
            
  
    
  </div>
          <div class="clear">
            <hr/>
          </div>
        </div>
    </div>
  </body>
</html>
